Almathera Ten Pack 3: CDPD 3/Almathera Ten on Ten - Disc 3: CDPD3.iso/scope/126-150/scopedisk127/textra/textra.doc

Text File | 1995-03-19 | 24KB | 555 lines

   This document describes TEXTRA, a very user-friendly text editor.
TEXTRA makes no claim at being the most powerful editor around, or the
fastest, smallest or any-OTHER-est.  Just pretty easy to use, that's
the goal.  And free.

TEXTRA is FreeWare.  I request, however, that this README file
accompany the executable if passed around.

If you are using TEXTRA to read this file, just point the mouse
at the arrow in the lower-right corner, and hold the left mouse button
down for a little.  You'll know when to let up.

TEXTRA was written in JForth Professional V2.0, which I recommend
highly.
                                            Thanx,  Mike Haas
26-Apr-89 executable size 60148
29-May-89   "    "    "   60864
22-Jul-89   "    "    "   61080
21-Oct-89   "    "    "   65208
05-Jan-90   "    "    "   69836
18-Feb-90   "    "    "   69400
---------------------------------------------------------------------------


              T A B L E     O F     C O N T E N T S
             ---------------------------------------

1.  INVOKING TEXTRA
    1.1  Invoking from Workbench or CLI
    1.2  Optional filename argument usage
    1.3  Shift-Double-clicking with "project"-type icons
    1.4  TEXTRA as the Default Tool for "Project"-type icons
2.  THE TEXTRA CURSOR
    2.1  Cursor appearance
    2.2  Positioning the cursor with the keyboard arrow keys
    2.3  Positioning the cursor with the mouse
    2.4  Quickly finding the cursor (function key F3)
3.  ENTERING TEXT INTO THE DOCUMENT
    3.1  Inserting text at the cursor location
    3.2  The RETURN key
         3.2.1  The "Auto-Indent" mode
    3.3  The BACKSPACE key
         3.3.1  The "Auto-BackSpace" mode
    3.4  The DEL key
    3.5  The TAB key
         3.5.1 Settable TAB Width
    3.6  The control-key filter and defeat feature (Function key F2)
4.  SELECTING A RANGE OF TEXT
    4.1  Using the mouse to select a range of characters
    4.2  Selecting text by double-clicking
    4.3  Operations on selected ranges
    4.4  Selecting more than the visible screen
    4.5  Quickly finding the selected range (function key F3)
    4.6  Extending a select range by SHIFT-clicking
5.  VIEWING PAGES
    5.1  The vertical scroll arrow gadgets
    5.2  The vertical scroll thumb gadget
    5.3  Scrolling the page with the keyboard arrow keys
    5.4  Keys that PAGE-up or PAGE-down
6.  TEXTRA WINDOWS
    6.1  Limitations
    6.2  The title bar
    6.3  The close gadget
    6.3  The sizing gadget
    6.4  The Window-Size-Toggle feature (Function key F1)
7.  TEXTRA MENUS
    7.1  Accessing the menus
    7.2  The "Project" menu
         7.2.1  Open A File...
         7.2.2  Open By Name...
         7.2.3  New File
         7.2.4  Revert To Saved
         7.2.5  Save File
         7.2.6  Save File As...
         7.2.7  Save All Files
         7.2.8  Close File
         7.2.9  About TEXTRA...
         7.2.10 Quit
    7.3  The "Edit" menu
         7.3.1  Cut
         7.3.2  Copy
         7.3.3  Paste
         7.3.4  Find
                7.3.4.1  String...
                7.3.4.2  Next Occurence
         7.3.5  Replace
                7.3.5.1  String...
                7.3.5.2  Next Occurence
         7.3.6  Case
                7.3.6.1  lower
                7.3.6.2  UPPER
                7.3.6.3  Capitalize
         7.3.7  Go to Line...
         7.3.8  Preferences...
    7.4  The "Windows" menu
         7.4.1  Dynamically-changing items
         7.4.2  Additional information
8.  TEXTRA GENERAL INFORMATION
    8.1  TEXTRA's use of Path and File names
    8.2  String Gadget Shortcuts
    8.3  TEXTRA String Gadgets and the RETURN key
    8.4  TEXTRA Requesters
    8.5  TEXTRA Keyboard Summary

---------------------------------------------------------------------------


1. INVOKING TEXTRA

1.1 TEXTRA, if double-clicked from WorkBench, will ask you to
select a filename soon after opening its first window.  TEXTRA
may be launched from CLI or SHELL with multiple filenames
as follows:

    1> TEXTRA <filename1> <filename2> ... <filenameX>

            OR

    1> RUN TEXTRA <filename1> <filename2> ... <filenameX>

1.2 If the optional filenames are not given, TEXTRA will ask you to
select one, as if double-clicked.  Select "CANCEL" if you do not
want to edit an existing file; the default name "Untitled" will
be assigned.

1.3 From Workbench, "Project" icons that are also selected when TEXTRA
is "SHIFT-Double-Clicked" will each be opened in their respective window.

1.4 A "Project" icon that has TEXTRA specified in its "Default Tool"
field will invoke TEXTRA, when double-clicked, and be opened in its
own window.

---------------------------------------------------------------------------


2. THE TEXTRA CURSOR

2.1 The current cursor location (where text will be inserted) is
represented by a thin line, of a different color than either text
or background.  If placed inside a text string, the cursor is
always BETWEEN two characters, showing clearly the sections that will
"spread apart" if something is typed into the window.

2.2 The cursor may be moved with the "arrow" keys on the keyboard; a
SHIFT-left-arrow or SHIFT-right-arrow will move the cursor to the
beginning or end of the current line, respectively.

2.3 The cursor may also be positioned by clicking the LEFT MOUSE
BUTTON, while the mouse cursor is over a part of the windows text area.

2.4 The display will move to the cursor location when the F3 key
is pressed.

---------------------------------------------------------------------------


3. ENTERING TEXT INTO THE DOCUMENT

3.1 As keys are typed at the keyboard, they are entered in the file
at the current cursor location, and the cursor is advanced by one.

3.2 The RETURN key inserts a new line, and moves the cursor there.

3.2.1 If the Auto-Indent mode is enabled (see section 7.3.8), the
cursor will advance to the same column as the 1st non-blank character
on the line above when the RETURN key is pressed.

3.3 The BACKSPACE deletes the character to the immediate left of the
cursor and backs the cursor up one column.  If the cursor is at the
leftmost column, the preceeding newline is removed and the cursor
moves up one line.

3.3.1 The Auto-BackSpace mode (section 7.3.8), if enabled, comes into
play when the cursor rests on the 1st non-blank character of a line.
Then, the line is "backed-up" by whatever it takes to line up with
the beginning of the text on the line above.  If the previous line
does not start to the left of the cursor line, the alignment is made
to the next line above that does.

3.4 The DELETE key removes the character to the immediate right of the
cursor.  If the cursor is at the end of a line, the newline is removed
and the next line moves up to merge with the current.

3.5 The TAB key advances the cursor to the next column that is an
even multiple of the TAB width value (section 3.5.1).

3.5.1 Settable TAB WIDTH (section 7.3.8) provides a way of changing
the default TAB width (8).  A string requester is presented, with
the currently installed size.  Maximum width accepted is 16.  The
setting applies to all windows.

3.6 Normally, TEXTRA will not allow control characters into the
window, permitting only visible or white-space characters.  This
feature can be temporarily defeated, for 1 character, by pressing F2.
Following F2, the next character will be accepted into the window
unfiltered.

---------------------------------------------------------------------------


4. SELECTING A RANGE OF TEXT

4.1 It is possible to mark a series of characters for the next
operation by "dragging" with the mouse.  The sequence is:

  a. Position the mouse over the 1st character of the desired series.
  b. Press the left mouse button and, while holding it down, move the
     mouse to the last character of the series (even if it is on another
     line).  Note that the characters between that clicked-on and wherever
     you move the mouse become "highlighted" (selected).
  c. Release the left mouse button when the desired range of characters
     is selected.

4.2 Any series of non-white characters will become selected if the
LEFT MOUSE BUTTON is double-clicked while the mouse cursor is
positioned over them.

4.3 When a range of text is selected, a subsequent operation will
affect the entire selected area.  For example, if a key is typed while
a range is selected, the range will be cut from the file, replaced by
that key.  Other examples are the BACKSPACE and DEL keys, which both
act to simply delete any selected area.  Certain items under the EDIT
menu, described later, also operate on any current range.

4.4 If, while selecting text, the mouse is moved near the bottom or top
of the window, available text in the appropriate direction will scroll
into view, becoming selected in the process.  Therefore, a select range
can extend past the visible limits of the window.

4.5 The display will move to the beginning of any currently-selected
range when the F3 key is pressed.

4.6 A select range may be established or size changed by holding
down the SHIFT key when clicking in the window.  If the click occurs
outside the current select range, the range is extended to there.
If inside, the end-point of the select range is adjusted to the
click-point.

---------------------------------------------------------------------------


5. VIEWING PAGES

5.1 The easiest method for moving through the file is to use the vertical
scroll bar on the right side of the window.  Single clicks of the left
mouse button on the arrows at either end move the document vertically,
one line at a time.  Holding the left button down on either yields a
continuous scroll.

5.2 The "thumb" in the middle of the scroll bar not only indicates the
visible-page-area relative to the total-file-size (by it's height),
but also the position within the file (by its vertical positioning).
It can also be "selected" with the left mouse button and moved as
a "coarse adjust".  The area immediately above and below the "thumb"
may be clicked with the left button as a "page-scroll" mechanism.

5.3 Another method by which text may be scrolled into view is to move
the cursor, via the keyboard "arrow" keys, to either the top or bottom
of the visible window.  Attempts to move the cursor "off the window"
will cause text in that direction to scroll.

5.4 Function keys F4 and F5 will PAGE the display down and up,
respectively.  The Shift-arrow-key combinations will also PAGE
the display in the appropriate direction AND position the cursor
to the middle of the new page.

---------------------------------------------------------------------------


6. TEXTRA WINDOWS

6.1 TEXTRA allows any number of windows, limited by the amount of
memory in your computer (most limiting is probably the amount of
available CHIP ram).  Textra lines can be up to 255 characters long,
number of lines limited by your total available memory (entire file
is kept in ram, FAST is grabbed first).

6.2 The title of each TEXTRA window is set to the full-pathname
of the file that was read in (or created).  This is also the name
of the file that will be written during a SAVE operation (unless
the "SAVE AS..." menu option is chosen, section 7.2.6).  If the
file has been modified since last saved, the filename will be
preceeded by a '*'.

6.3 Each window includes a standard Intuition close gadget, which
performs the same action as the "CLOSE FILE" menu option.  See the
discussion on "CLOSE FILE" (section 7.2.8) for more information.

6.4 The "sizing" gadget in the lower-right hand corner of each window
may be used to adjust the dimensions of that window, up to the
full-screen limitations of the Workbench.

6.5 Function key F1 may be used as a "window-size-toggle" between
default size (when F1 was first hit) and full-screen (as per current
screen resolution settings).  This is particularly
useful when Workbench is in 400 line interlace.

(NOTE: if F1 is used to expand the screen, and the size gadget is
       then clicked without actually changing size, the default-size
       becomes equal to the full-screen-size.  This will make F1
       non-functional until the size gadget is used to actually
       change window size.  To avoid this, don't click on the
       sizing gadget when the window is full-size.  Use F1 to
       get back to normal size).

---------------------------------------------------------------------------


7. TEXTRA MENUS

7.1 3 menus are available and present themselves when the RIGHT
MENU BUTTON is depressed and held.  Some menu items may also
be activated by simultaneously pressing the RIGHT AMIGA key
and the one that is specified in the menu item text.

7.2 The "Project" Menu

7.2.1 OPEN A FILE... opens a new window with a full file-selector
requester and buttons that allow quick access to the top 6 disk
devices (like DF0:).  The PARENT button changes the current directory
to the level above the one being displayed.  The KEYBOARD button
presents the user with a string requester into which a file or
directory specification may be typed.  The CANCEL button exits the
requester with no other action while the OK button enters the file
or directory selected in the list box (the same as CANCEL if nothing
is selected).  Double-clicking one of the names performs the same
action as the OK button.

7.2.2 OPEN BY NAME... opens a new window, then presents a string
requester for specifying a filename (directory names are invalid
in this requester) from the keyboard.  This bypasses the directory
scan for the list of names, which can take time on large directories,
especially on floppy drives.  Note that the current directory of
the requester is that of the spawning window.

7.2.3 NEW FILE opens a window without specifying a filename; the
default name "Untitled" is assigned, at the directory level of
the spawning window.

7.2.4 REVERT TO SAVED causes the read-in version of the selected
file to be discarded, replaced by the version that was last-saved
to disk.  A verification requester is presented to make sure this
is not done accidently.

7.2.5 SAVE FILE causes the currently-selected file to be written to
disk, if modified.  If the file has not been changed (no '*' before
the title), this menu item is disabled.

7.2.6 SAVE FILE AS... allows saving the currently selected file under
a different name.  After this operation, the title bar will contain
the new name, and it will have been created on disk.  If the
specified file already exists, the user is warned and given a
chance to abort.  The "USE LIST" button will present a full
file-requester through which an existing file may be selected with
the mouse.  This requester is very similar in operation to the
"OPEN FILE..." requester; all buttons work the same, except the
OK button will overwrite the selected file (as does double-clicking
a filename).

7.2.7 SAVE ALL FILES causes all files that have been modified and not
saved to be written to disk.  If there are no modified files, this
menu item is disabled.

7.2.8 CLOSE FILE will check if the file has been modified but not
saved and warn the user if so.  Note that closing TEXTRA's last window
will cause it to exit; a requester will notify you if you are closing
the last window and give you the chance to abort.

7.2.9 ABOUT TEXTRA is self-explanatory.

7.2.10 QUIT will exit TEXTRA, closing all files in the process.  All
files that have been modified but not saved will issue a notification
requester, providing the opportunity to save at that time.

7.3 The "Edit" Menu

7.3.1 CUT removes the selected range of characters from the
currently-selected file, but saves them in the TEXTRA clip area
(TEXTRA does not interface with the standard Amiga Clipboard
Device...future versions may do so).  The previous contents of
the TEXTRA clip area are lost.  If there is no select range,
this menu item is disabled.

7.3.2 COPY moves the selected range of characters of the
currently-selected file to the TEXTRA clip area, but does not
remove them from the file.  The previous contents of the TEXTRA
clip area are lost.  If there is no select range, this menu
item is disabled.

7.3.3 PASTE inserts whatever is in the TEXTRA clip area into the
currently-selected file, at the current cursor location.  If a select
range is active in this file, it is deleted before the insertion takes
place.  There is no effect on the contents of the TEXTRA clip area.
It nothing has been placed into the TEXTRA clip area (via CUT or COPY),
this menu item is disabled.

7.3.4 FIND presents a sub-menu with 2 choices:

7.3.4.1 STRING... presents a requester prompting for the string
to search for, ignoring character case.  The string gadget will, as
a default, contain the previous string searched for IN THAT WINDOW
(empty if none).  However, if a range of characters is selected that
is ALL ON ONE LINE, it will supercede any previously-searched-for
string as the default for the string gadget.  The search begins just
past the current cursor location or selected range of characters.

7.3.4.2 NEXT OCCURENCE conducts another case-insensitive search
for the same text string that had previously been searched for.
If no search had yet been conducted the "STRING..." requester is presented.

7.3.5 REPLACE presents a sub-menu with 2 choices:

7.3.5.1 STRING... presents a double-string-requester, prompting for
both the string to conduct a case-insensitive search for, and a second
string, to replace the first with, when found.  The RETURN key will
toggle the selected string gadget.  The user may optionally replace
all instances of the found string (with the "ALL!" button), just the
next one found (via the "ONCE" button), or abort (via "CANCEL").  The
search begins just past the current cursor location or selected range
of characters.

7.3.5.2 NEXT OCCURENCE conducts another "REPLACE" operation, using the
same strings that were used last time.  If none exist, the "STRING..."
requester is presented.

7.3.6 CASE presents a sub-menu with 3 choices:

7.3.6.1 LOWER exhibits 2 behaviors depending on whether an area
is selected or not.  If there is, the entire selected area is converted
to lower case.  If not, the next word after the cursor is searched for
and converted to lower case if found.

7.3.6.2 UPPER exhibits 2 behaviors depending on whether an area
is selected or not.  If there is, the entire selected area is converted
to upper case.  If not, the next word after the cursor is searched for
and converted to upper case if found.

7.3.6.3 CAPITALIZE exhibits 2 behaviors depending on whether an area
is selected or not.  If there is, each word in the selected area is
located and capitalized.  If not, the next word after the cursor is
located and capitalized.

7.3.7 GO TO LINE... presents a string requester prompting for the
desired line number, with the initial string gadget contents being
equal to the current cursor line (or the beginning of any selected
range).  First line of file is considered line 1.

7.3.8 PREFERENCES... presents a requester allowing the selection of
modes and settings, specifically, the "Auto-Indent" mode (section
3.2.1), the "Auto-BackSpace" mode (section 3.3.1) and the TAB WIDTH
(section 3.5.1).  The USE button causes the currently displayed
settings to go into effect.  The USE+SAVE button does the USE function,
and also saves the current settings in a file called "Textra.prefs".
This file is written to the TEXTRA "startup directory".  This is the
directory that was either current if TEXTRA was invoked from CLI, or
the one that contained TEXTRA if double-clicked from Workbench.  The
CANCEL button causes any currently displayed settings that have been
changed, to be discarded.  If the PREFERENCES requester is active, this
menu item is disabled.

7.4 The "Windows" Menu

7.4.1 One item exists in the "WINDOWS" menu for each open file, the
menu item text being the same as the title bar for the associated
window.  Selecting an item makes it the current window, if not
already.

7.4.2 Additionally, the text includes the "*" character before the
filename if the file has been modified since last written to disk.
A checkmark preceeds the item representing the current file.

---------------------------------------------------------------------------


8. TEXTRA GENERAL INFORMATION

8.1 TEXTRA always fully expands a specified file or directory name
and uses that form to again find the file, if necessary.  For example,
you may have typed in "DF1:MyFile" as the filename, but the window
title will substitute the name of the volume, possibly "MyDisk:MyFile".
This is almost always desirable, because if TEXTRA saved "DF1:", you
might unknowingly save it to the wrong disk, just because you switched
the disk in that drive.  TEXTRA will ask you specifically for the same
name.
   The only situation you should be aware of is WHEN YOU HAVE TWO
DISKS OF THE SAME NAME in your system.  In this case, AmigaDOS can
sometimes choose the wrong disk when TEXTRA passes the full-pathname
to it.
  In the above example, we could save it to the wrong disk if the disk
in DF0: is also named "MyDisk:" (a backup, perhaps???).  This is not
caused by TEXTRA, but can happen anytime in AmigaDOS that you use the
full-pathname to specify a file.

8.2 Intuition provides two String Gadget shortcuts that can be
useful to the TEXTRA user.  TEXTRA string gadgets that provide
a default text string when they appear will revert back to this
string whenever "Right Amiga-Q" is pressed.  The "Right Amiga-X"
combination will clear any displayed string.

8.3 For all string gadgets but one, the RETURN key will perform
the same action  as the "OK" button.  The one exception is the
"REPLACE" double-string requester, where the RETURN key toggles between
the two string gadgets.

8.4 TEXTRA Requesters are attached to (drawn in) the window that they
have been spawned from.  The advantage is that multiple requesters
are possible...you can select and work in another file even if
the previous window is waiting for you to answer a question.  Every
window can, in fact, have an open requester.
  Note that, if your window is too small, you may have to expand
its size to inter-operate with a given requester.  Unfortunately,
since the Intuition requester mechanism locks out my console events
from that window, I can't process the F1 key, and you have to do
this with the mouse.
  (Intuition should give the application a looksee at the keys before
using them in a string gadget, throwing them away or whatever.  The
application could reply with a boolean, whether it wants the requester
to use it or not.  This could even default to NO_BOOLEAN if not specified
previously by the caller as a requester mode.  Maybe a REQ_KEY_VERIFY
event. Oh well, let's re-design Intuition another time).

8.5 Keyboard Summary:

    F1 - Window Size Toggle (6.4)
    F2 - Keyboard Filter Defeat (3.6)
    F3 - Page to Cursor or Beginning of Select Range (4.5)
    F4 - Display next page (5.4)
    F5 - Display previous page (5.4)

    Shift-Left-arrow  - Cursor to beginning of current line (2.2)
    Shift-Right-arrow - Cursor to end of current line (2.2)
    Shift-Up-arrow    - Display previous page, cursor to middle (5.4)
    Shift-Down-arrow  - Display next page, cursor to middle (5.4)

    Right-Amiga-O - Open existing file via file requester (7.2.1)
    Right-Amiga-P - Open existing file by typing its name (7.2.2)
    Right-Amiga-[ - Open a new file (7.2.3)
    Right-Amiga-S - Save the current file (7.2.5)
    Right-Amiga-X - Cut selected text, save in clip area (7.3.1)
    Right-Amiga-C - Copy selected text into clip area (7.3.2)
    Right-Amiga-V - Paste clip area into file (7.3.3)
    Right-Amiga-F - Find string in any case (7.3.4.1)
    Right-Amiga-N - Find the next occurance of same string (7.3.4.2)
    Right-Amiga-R - Replace string with another (7.3.5.1)
    Right-Amiga-T - Find & replace same string again (7.3.5.2)
    Right-Amiga-L - Set text or next word to lower case (7.3.6.1)
    Right-Amiga-U - Set text or next word to upper case (7.3.6.2)
    Right-Amiga-K - Capitalize words or next word (7.3.6.3)
    Right-Amiga-G - Go to a specific line (7.3.7)

    Requester control...

    Right-Amiga-X - Clear text in string requester (8.2)
    Right-Amiga-Q - Restore original string requester text (8.2)